=begin pod :tag<index>

=TITLE Pragmas

=SUBTITLE Special modules for special use

In Perl 6, B<pragmas> are core modules used to either identify a
specific version of Perl 6 to be used or to modify its normal behavior
in some way.  They are "use"ed in your code just as normal modules:

=begin code
use v6.c;
=end code

Following is a list of pragmas with a short description of each
pragma's purpose or a link to more details about its use.  (Note:
Pragmas marked "[NYI]" are not yet implemented, and those marked "[TBD]"
are to be defined later.)

=comment The following should be a table but formatting in tables is
not yet rendered properly.

=item X<B<MONKEY-GUTS>|MONKEY-GUTS>

This pragma is not currently part of any Perl 6 specification, but is present
in Rakudo as a synonym to C<use nqp> (see below).

=item X<B<MONKEY-SEE-NO-EVAL>|MONKEY-SEE-NO-EVAL> L<EVAL|/routine/EVAL>

=item X<B<MONKEY-TYPING>|MONKEY-TYPING> L<augment|/syntax/augment>

=item X<B<experimental>|experimental> allows use of experimental features

=item X<B<fatal>|fatal>

A lexical pragma that makes L<Failures|/type/Failure> returned from routines
fatal. For example, prefix C<+> on a L<Str> coerces it to L<Numeric>, but will
return a L<Failure> if the string contains non-numeric characters. Saving that
L<Failure> in a variable prevents it from being sunk, and so the first code
block below reaches the C<say $x.^name;> line and prints C<Failure> in output.

In the second block, the C<use fatal> pragma is enabled, so the C<say> line is
never reached because the L<Exception> contained in the L<Failure> returned from
prefix C<+> gets thrown and the C<CATCH> block gets run, printing the C<Caught...>
line. Note that both blocks are the same program and C<use fatal> only affects
the lexical block it was used in:

    {
        my $x = +"a";
        say $x.^name;
        CATCH { default { say "Caught {.^name}" } }
    } # OUTPUT: «Failure␤»

    {
        use fatal;
        my $x = +"a";
        say $x.^name;
        CATCH { default { say "Caught {.^name}" } }
    } # OUTPUT: «Caught X::Str::Numeric␤»

Inside of a L«C<try> blocks|/language/exceptions#index-entry-try_blocks-try», the
C<fatal> pragma is enabled by default, and you can I<disable> it with C<no fatal>:

    try {
        my $x = +"a";
        say $x.^name;
        CATCH { default { say "Caught {.^name}" } }
    } # OUTPUT: «Caught X::Str::Numeric␤»

    try {
        no fatal;
        my $x = +"a";
        say $x.^name;
        CATCH { default { say "Caught {.^name}" } }
    } # OUTPUT: «Failure␤»

=item X<B<internals>|internals> [NYI]

=item X<B<invocant>|invocant> [NYI]

=item X<B<lib>|lib> L<Finding Modules|/language/modules#Finding_Modules>

=item X<B<newline>|newline>

Set the value of the L<$?NL|/language/variables#Compile-time_variables> constant
in the scope it is called.  Possible values are C<:lf> (which is the default,
indicating Line Feed), C<:crlf> (indicating Carriage Return, Line Feed) and
C<:cr> (indicating Carriage Return).

=item X<B<nqp>|nqp>

Use at your own risk.

This is a Rakudo-specific pragma. With it, Rakudo provides access to the
L<nqp opcodes|https://github.com/perl6/nqp/blob/master/docs/ops.markdown>
in a top level namespace:

    use nqp;
    nqp::say("hello world");

This uses the underlying nqp C<say> opcode instead of the Perl 6 routine. This
pragma may make your code rely on a particular version of nqp, and since
that code is not part of the Perl 6 specification, it's not guaranteed to
be stable. You may find a large number of usages in the Rakudo core,
which are used to make the core functionality as fast as possible.
Future optimizations in the code generation of Rakudo may obsolete these
usages.

=item X<B<parameters>|parameters> [NYI]

=item X<B<precompilation>|precompilation>

The default allows precompilation of source code, specifically if used in a
module.  If for whatever reason you do not want the code (of your module) to
be precompiled, you can use C<no precompilation>.  This will prevent the
entire compilation unit (usually a file) from being precompiled.

=item X<B<soft>|soft> L<Re-dispatching|/language/functions#Re-dispatching>, L<inlining|/language/functions#index-entry-use_soft_(pragma)>

=item X<B<strict>|strict>

C<strict> is the default behavior, and requires that you declare variables
before using them. You can relax this restriction with C<no>.

=for code
    no strict; $x = 42; # OK

=item X<B<trace>|trace>

When C<use trace> is activated, any line of code executing will be written to
STDERR.  You can use C<no trace> to switch off the feature, so this only happens
for certain sections of code.

=item X<B<v6>|v6> L<Writing Tests|/language/testing#Writing_tests>

=item X<B<variables>|variables>
 L<Defined Variables Pragma|/language/variables#Default_Defined_Variables_Pragma>

=item X<B<worries>|worries>

Lexically controls whether compile-time warnings generated by the
compiler get shown. Enabled by default.

    =begin code :lang<text>
    $ perl6 -e 'say :foo<>.Pair'
    Potential difficulties:
      Pair with <> really means an empty list, not null string; use :foo('') to represent the null string,
        or :foo() to represent the empty list more accurately
      at -e:1
      ------> say :foo<>⏏.Pair
    foo => Nil

    $ perl6 -e 'no worries; say :foo<>.Pair'
    foo => Nil
    =end code

=item Other pragma under discussion

The following pragma's have been discussed in the past, but will most likely
never see any functionality implemented for them:

MONKEY-BARS, MONKEY-BRAINS, MONKEY-BUSINESS, MONKEY-SHINE, MONKEY-TRAP,
MONKEY-WRENCH

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
